Plan 89: TOC generator directive and MDS035 auto-fix - #147
Merged
Conversation
Follow-up to plan 88. Adds a <?toc?>...<?/toc?> generated-section directive (MDS036) that emits a nested list of the document's headings, and upgrades MDS035 from detection-only to auto-fix by rewriting the four detected renderer-specific TOC tokens into <?toc?> blocks that MDS036 then populates on the next fix pass. Design notes: - New rule MDS036 "toc" (meta, default-enabled, fixable) built on the shared internal/archetype/gensection engine that MDS019 catalog already uses. - Parameters: min-level (default 2, matches Python-Markdown [TOC]) and max-level (default 6). Output is GitHub-slug links. - MDS035 Fix leaves [TOC] untouched when a matching link reference definition makes it resolve to a real link. - Relies on mdsmith's existing multi-pass fix; falls back to emitting populated content directly from MDS035 only if that proves brittle.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #147 +/- ##
=======================================
Coverage 86.35% 86.35%
=======================================
Files 94 94
Lines 10149 10149
=======================================
Hits 8764 8764
Misses 903 903
Partials 482 482 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
Adds roadmap plan 89 describing a native <?toc?> generated-section directive and an accompanying MDS035 auto-fix that migrates renderer-specific TOC tokens to <?toc?> blocks.
Changes:
- Added plan 89 design/spec document for
<?toc?>(MDS036) and MDS035 auto-fix/multi-pass behavior. - Updated
PLAN.mdcatalog output to include the new plan entry.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| plan/89_toc-generator-directive.md | New plan detailing directive syntax, slugging rules, MDS036 rule behavior, and MDS035 fix strategy. |
| PLAN.md | Adds plan 89 to the generated roadmap table. |
jeduden
added
queue:active
Owner
Author
|
🟢 Merge Queue — picked up This PR is in the queue and will be batched with other Next: No action needed — you'll get another comment when CI starts on the batch. View merge queue run. |
Owner
Author
|
🔵 Merge Queue — CI running Merged into batch branch Next: No action needed — you'll be notified when CI completes. |
Owner
Author
|
✅ Merge Queue — merged This PR landed on Next: Done — nothing more to do here. |
jeduden
removed
the
queue:active
jeduden
pushed a commit
that referenced
this pull request
Apr 19, 2026
- Renumber MDS036 → MDS037 for the toc rule. Plan 51 shipped first and took MDS036 for max-section-length; MDS034 stays reserved for plan 86. - Replace the hand-rolled slug algorithm with a directive to move the existing slugify / duplicate-disambiguation logic out of crossfilereferenceintegrity into a shared helper (internal/mdtext) that both rules call. Drops incorrect goldmark-meta reference. - Drop fictitious <?listindent?> directive reference; describe indentation as MDS016 list-indent.spaces (default 2). - Correct MDS015 interaction note: MDS015 only covers fenced code blocks, so blank-line padding around <?toc?> is MDS035 Fix's responsibility. - Unify the canonical empty-body form as <?toc?>\n<?/toc?> throughout design, tasks, and acceptance criteria. - Add task 1 (move slug helper to shared package) and renumber downstream tasks. - Grammar pass: "GitHub-style" consistently. Follow-up to PR #147 (already merged).
2 tasks
Owner
Author
|
Addressed all six Copilot review threads in follow-up PR #148. Summary of fixes:
|
jeduden
pushed a commit
that referenced
this pull request
Apr 20, 2026
- Renumber MDS036 → MDS037 for the toc rule. Plan 51 shipped first and took MDS036 for max-section-length; MDS034 stays reserved for plan 86. - Replace the hand-rolled slug algorithm with a directive to move the existing slugify / duplicate-disambiguation logic out of crossfilereferenceintegrity into a shared helper (internal/mdtext) that both rules call. Drops incorrect goldmark-meta reference. - Drop fictitious <?listindent?> directive reference; describe indentation as MDS016 list-indent.spaces (default 2). - Correct MDS015 interaction note: MDS015 only covers fenced code blocks, so blank-line padding around <?toc?> is MDS035 Fix's responsibility. - Unify the canonical empty-body form as <?toc?>\n<?/toc?> throughout design, tasks, and acceptance criteria. - Add task 1 (move slug helper to shared package) and renumber downstream tasks. - Grammar pass: "GitHub-style" consistently. Follow-up to PR #147 (already merged).
jeduden
added a commit
that referenced
this pull request
Apr 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds plan 89 to the mdsmith roadmap, which outlines the implementation of a native
<?toc?>directive for generating table of contents from document headings, along with upgrading MDS035 to auto-fix renderer-specific TOC tokens by converting them to the new directive.Changes
Added plan/89_toc-generator-directive.md: Comprehensive design document for the TOC generator feature including:
min-levelandmax-levelparameters[TOC],[[_TOC_]],[[toc]],${toc}to<?toc?>blocks)Updated PLAN.md: Added plan 89 entry to the roadmap table
Implementation Details
The plan leverages mdsmith's existing generated-section machinery (used by
<?catalog?>and<?include?>) to implement the TOC directive. Key design decisions:<?toc?>blocks, then MDS036 populates them in a subsequent passmin-level: 2excludes document title, matching Python-Markdown behaviorhttps://claude.ai/code/session_01T569bC9ogHHf5A6Cgxn9NW